docs: Add network_setup.txt file explaining bridge setup.

Signed-off-by: Daniel P. Berrange <berrange@redhat.com>

diff --git a/docs/misc/network_setup.txt b/docs/misc/network_setup.txt
new file mode 100644 (file)
index 0000000..4d9349d
--- /dev/null
+++ b/docs/misc/network_setup.txt
@@ -0,0 +1,195 @@
+Native OS bridge configuration
+==============================
+
+The traditional "network-bridge" script attempts to modify existing active
+network interfaces to enable bridging. For non-trivial network configurations
+though this can be error prone, and the temporary disruption to network
+connectivity can upset some applications.  This document outlines how to
+configure bridging using an OS' native network configuration files.
+
+Disabling Xen's network scripts
+-------------------------------
+
+The first step is to check XenD's network bridge is disabled by
+editing /etc/xen/xend-config.sxp and changing the line
+
+ (network-script network-bridge)
+
+To be
+
+ (network-script /bin/true)
+
+
+Fedora/RHEL Bridging
+====================
+
+This outlines how to setup bridging using standard network initscripts
+present in Fedora or RHEL distros and their derivatives
+
+
+Disabling NetworkManager
+------------------------
+
+As of time of writing (Fedora 11) NetworkManager does not support bridging,
+so it is neccessary to disable it, and revert to "classic" network initscripts
+
+ # chkconfig NetworkManager off
+ # chkconfig network on
+ # service NetworkManager stop
+ # service network start
+
+NB, as an alternative to turning off NetworkManager, you can also add a line
+"NM_CONTROLLED=no" to the ifcfg-XXX scripts below
+
+Creating network initscripts
+----------------------------
+
+In the /etc/sysconfig/network-scripts directory it is necccessary to create
+2 config files. The first (ifcfg-eth0) defines your physical network interface,
+and says that it will be part of a bridge:
+
+# cat > ifcfg-eth0 <<EOF
+DEVICE=eth0
+HWADDR=00:16:76:D6:C9:45
+ONBOOT=yes
+BRIDGE=br0
+EOF
+
+Obviously change the HWADDR to match your actual NIC's address. You may also
+wish to configure the device's MTU here using e.g. MTU=9000.
+
+The second config file (ifcfg-br0) defines the bridge device:
+
+# cat > ifcfg-br0 <<EOF
+DEVICE=br0
+TYPE=Bridge
+BOOTPROTO=dhcp
+ONBOOT=yes
+DELAY=0
+EOF
+
+WARNING: The line TYPE=Bridge is case-sensitive - it must have uppercase
+'B' and lower case 'ridge'
+
+After changing this restart networking (or better still reboot)
+
+ # service network restart
+
+
+The final step is to configure iptables to allow all traffic to be
+forwarded across the bridge
+
+# echo "-I FORWARD -m physdev --physdev-is-bridged -j ACCEPT" > /etc/sysconfig/iptables-forward-bridged
+# lokkit --custom-rules=ipv4:filter:/etc/sysconfig/iptables-forward-bridged
+# service libvirtd reload
+
+Alternatively, you can prevent bridged traffic getting pushed through
+the host's iptables rules completely. In /etc/sysctl.conf add
+
+ # cat >> /etc/sysctl.conf <<EOF
+ net.bridge.bridge-nf-call-ip6tables = 0
+ net.bridge.bridge-nf-call-iptables = 0
+ net.bridge.bridge-nf-call-arptables = 0
+ EOF
+ # sysctl -p /etc/sysctl.conf
+
+You should now have a "shared physical device", to which guests can be
+attached and have full LAN access
+
+ # brctl show
+ bridge name     bridge id               STP enabled     interfaces
+ br0             8000.000e0cb30550       no              eth0
+
+
+
+Debian/Ubuntu Bridging
+=======================
+
+This outlines how to setup bridging using standard network interface config files
+on Debian / Ubuntu distributions and their derivatives
+
+Disabling NetworkManager
+------------------------
+
+Stop network manager
+
+ sudo /etc/dbus-1/event.d/26NetworkManagerDispatcher stop
+ sudo /etc/dbus-1/event.d/25NetworkManager stop
+
+Create two files with only the word 'exit' in them. These files are:
+
+ /etc/default/NetworkManager
+ /etc/default/NetworkManagerDispatcher
+
+
+Altering the interface config
+-----------------------------
+
+First take down the interface you wish to bridge
+
+ ifdown eth0
+
+Edit /etc/network/interfaces and find the config for the physical
+interface, which looks something like
+
+ allow-hotplug eth0
+ iface eth0 inet static
+        address 192.168.2.4
+        netmask 255.255.255.0
+        network 192.168.2.0
+        broadcast 192.168.2.255
+        gateway 192.168.2.2
+
+Remove the 'allow-hotplug eth0' line, replacing it with 'auto br0',
+and change the next line with iface name to 'br0', so it now starts
+with
+
+ auto br0
+ iface br0 inet static
+
+And then define the interface as being a bridge and specify its ports
+
+       bridge_ports eth0
+       bridge_stp off
+       bridge_maxwait 5
+
+The complete config should now look like
+
+ auto br0
+ iface br0 inet static
+         address 192.168.2.4
+         netmask 255.255.255.0
+         network 192.168.2.0
+         broadcast 192.168.2.255
+         gateway 192.168.2.2
+         bridge_ports eth0
+         bridge_stp off
+         bridge_maxwait 5
+
+The interface can now be started with
+
+ ifup br0
+
+Finally add the '/etc/sysctl.conf' settings
+
+net.bridge.bridge-nf-call-ip6tables = 0
+net.bridge.bridge-nf-call-iptables = 0
+net.bridge.bridge-nf-call-arptables = 0
+
+And then load the settings with
+
+ sysctl -p /etc/sysctl.conf
+
+
+You should now have a "shared physical device", to which guests
+can be attached and have full LAN access
+
+ # brctl show
+ bridge name     bridge id               STP enabled     interfaces
+ br0             8000.000e0cb30550       no              eth0
+
+
+Other operating systems / distributions
+=======================================
+
+[...send patches to this file with instructions....]